Node / ReticulumProjects / MeshChatX.git / files / docs / agents / conventions / backend.md

Displaying Rendered • View raw • Download

Applies when editing T383838meshchatx/**/*.py.

• Prefer T383838uv run / T383838task for pytest and ruff.

• HTTP handlers: return 400 for T383838ValueError / bad input, 503 for retryable SQLite/Landlock unavailability, 500 only for unexpected failures.

• Thin HTTP handlers live under T383838meshchatx/src/backend/http/routes/. Parse the request, call a manager or app method, map errors. Do not add new business logic in route modules.

• Shared HTTP helpers: T383838backend/http/errors.py, T383838backend/http/context.py, T383838backend/http/middleware.py, T383838backend/http/register.py, T383838backend/http/live_names.py.

• T383838errors.py and T383838context.py are intentional scaffolding. Adopt T383838http_bad_request / T383838http_unavailable / T383838http_unexpected only when a handler is already thin. Do not refactor fat handlers only to call them.

• When splitting or moving handlers among T383838routes/<domain>.py, follow T383838docs/agents/skills/meshchat-orchestration-split/SKILL.md and T383838docs/agents/module-ownership.md. Mechanical moves only (no behaviour change in the same change).

• Multipart parsers must not assume field order.

• SQLite worker connections must set T383838temp_store=MEMORY in T383838DatabaseProvider (Landlock-safe).

• Under Landlock, memory-pressure must not force FILE temp for conversation queries.

• Subprocess or user-local CLI features must remain usable under Landlock. Extend T383838landlock_sandbox.py read/RW roots and add a probe in T383838tests/backend/test_landlock_integration_surfaces.py (see T383838landlock-sqlite skill).

• Keep conversation list queries slim: truncate content, derive attachment flags in SQL, avoid shipping full T383838fields blobs.

• Identity restore validates size and empty payloads. Preserve existing identity metadata on re-import.

• No backticks in code comments. Prefer plain words or quoted identifiers.

• RRC / LXMF / LXST changes: open the matching skill under T383838docs/agents/skills/ and run oracle-style tests when behaviour changes.

• Local filesystem browse/upload/download/delete: follow T383838docs/agents/conventions/path-jail.md and T383838docs/agents/skills/path-jail-local-fs/SKILL.md.